Telegram Bot Builder
Comprehensive guidance for building Telegram bots using the Bot API (v9.4). Covers both Node.js and Python ecosystems with production-ready patterns for authentication, messaging, keyboards, media handling, payments, inline mode, webhooks, and deployment.
When to Use This Skill
Use this skill when:
Building a new Telegram bot from scratch
Integrating Telegram messaging into an existing application
Setting up webhooks or long polling for bot updates
Creating interactive menus with inline keyboards and callback queries
Handling media (photos, videos, documents, stickers)
Implementing Telegram Payments or Telegram Stars
Building inline mode functionality
Managing groups, channels, or forum topics via bot
Deploying bots to production (Docker, PM2, serverless)
Core Concepts
Authentication
Every bot has a unique token obtained from
@BotFather
. Token format:
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
.
All API calls go to:
https://api.telegram.org/bot
.env file
BOT_TOKEN
123456 :ABC-DEF1234ghIkl-zyx57W2v1u123ew11 Store the token in environment variables. Never commit it to source code. Receiving Updates: Polling vs Webhook Long Polling ( getUpdates ) - Simpler, no HTTPS required, ideal for development: // Node.js with node-telegram-bot-api const bot = new TelegramBot ( process . env . BOT_TOKEN , { polling : true } ) ;
Python with python-telegram-bot
app
Application
.
builder
(
)
.
token
(
os
.
getenv
(
"BOT_TOKEN"
)
)
.
build
(
)
app
.
run_polling
(
)
Webhook
(
setWebhook
) - Better for production, lower latency, requires HTTPS (ports 443, 80, 88, or 8443):
bot
.
setWebHook
(
'https://yourdomain.com/webhook'
,
{
secret_token
:
SECRET
}
)
;
Choose polling for development and small bots. Choose webhooks for production deployments handling high traffic.
Message Types & Formatting
Send text with
sendMessage
. Supported parse modes:
HTML
:
bold
,
italic
,
code
,
block
- ,
- link
- ,
spoiler - MarkdownV2
- :
- bold
- ,
- italic
- ,
code- ,
block- ,
- link
- ,
- ||spoiler||
- . Requires escaping:
- _*~>#+-=|{}.!
- Prefer HTML for easier escaping. Use MarkdownV2 when simpler formatting suffices.
- Keyboards & Interactive Elements
- Inline Keyboard
- - Buttons attached to messages:
- bot
- .
- sendMessage
- (
- chatId
- ,
- 'Choose:'
- ,
- {
- reply_markup
- :
- {
- inline_keyboard
- :
- [
- [
- {
- text
- :
- 'Option A'
- ,
- callback_data
- :
- 'a'
- }
- ,
- {
- text
- :
- 'Option B'
- ,
- callback_data
- :
- 'b'
- }
- ]
- ,
- [
- {
- text
- :
- 'Visit Site'
- ,
- url
- :
- 'https://example.com'
- }
- ]
- ]
- }
- }
- )
- ;
- Reply Keyboard
- - Custom keyboard below input field:
- bot
- .
- sendMessage
- (
- chatId
- ,
- 'Choose:'
- ,
- {
- reply_markup
- :
- {
- keyboard
- :
- [
- [
- {
- text
- :
- '📊 Stats'
- }
- ,
- {
- text
- :
- '⚙️ Settings'
- }
- ]
- ]
- ,
- resize_keyboard
- :
- true
- ,
- one_time_keyboard
- :
- true
- }
- }
- )
- ;
- Handle inline button presses with
- callback_query
- . The
- callback_data
- field is limited to 64 bytes. Always call
- answerCallbackQuery
- to dismiss the loading indicator.
- Sending Media
- // Photo (file_id, URL, or upload)
- bot
- .
- sendPhoto
- (
- chatId
- ,
- 'https://example.com/photo.jpg'
- ,
- {
- caption
- :
- 'A photo'
- }
- )
- ;
- // Document
- bot
- .
- sendDocument
- (
- chatId
- ,
- fs
- .
- createReadStream
- (
- './file.pdf'
- )
- ,
- {
- caption
- :
- 'Report'
- }
- )
- ;
- // Album (2-10 items)
- bot
- .
- sendMediaGroup
- (
- chatId
- ,
- [
- {
- type
- :
- 'photo'
- ,
- media
- :
- 'https://example.com/1.jpg'
- ,
- caption
- :
- 'First'
- }
- ,
- {
- type
- :
- 'photo'
- ,
- media
- :
- 'https://example.com/2.jpg'
- }
- ]
- )
- ;
- Three ways to specify files:
- file_id
- (reuse previously uploaded), HTTP URL (Telegram downloads it), or multipart upload. File limits: 50MB upload, 20MB download via Bot API.
- Conversation State
- For multi-step interactions (registration, forms, wizards), maintain conversation state per chat:
- Node.js
-
- Use a
- Map
- or Redis to track
- { step, data }
- per
- chatId
- Python
-
- Use
- ConversationHandler
- from
- python-telegram-bot
- (built-in state machine)
- See
- reference/patterns_and_examples.md
- for complete conversation flow implementations.
- Error Handling
- Handle common error scenarios:
- 429 Too Many Requests
-
- Read
- retry_after
- from response, wait, then retry
- 403 Forbidden
-
- Bot was blocked by user or removed from chat
- 400 Bad Request
-
- Invalid parameters (check
- description
- field)
- 409 Conflict
-
- Another bot instance using same token with polling
- Rate limits: ~30 messages/second to different chats, ~20 messages/minute to same group. Implement exponential backoff for retries.
- Bot Commands
- Register commands visible in the Telegram menu:
- bot
- .
- setMyCommands
- (
- [
- {
- command
- :
- 'start'
- ,
- description
- :
- 'Start the bot'
- }
- ,
- {
- command
- :
- 'help'
- ,
- description
- :
- 'Show help'
- }
- ,
- {
- command
- :
- 'settings'
- ,
- description
- :
- 'Bot settings'
- }
- ]
- )
- ;
- Commands can be scoped to specific chats, users, or languages using
- BotCommandScope
- .
- Common Patterns
- Quick Start (Node.js)
- mkdir
- my-bot
- &&
- cd
- my-bot
- npm
- init
- -y
- npm
- install
- node-telegram-bot-api dotenv
- echo
- "BOT_TOKEN=your_token_here"
- >
- .env
- Quick Start (Python)
- mkdir
- my-bot
- &&
- cd
- my-bot
- pip
- install
- python-telegram-bot python-dotenv
- echo
- "BOT_TOKEN=your_token_here"
- >
- .env
- Popular Libraries
- Language
- Library
- Style
- Best For
- Node.js
- node-telegram-bot-api
- Callback-based
- Simple bots, quick prototypes
- Node.js
- grammy
- Middleware-based
- Complex bots, plugins
- Node.js
- telegraf
- Middleware-based
- Mature ecosystem
- Python
- python-telegram-bot
- Handler-based
- Full-featured, conversations
- Python
- aiogram
- Async-first
- High-performance async bots
- Key API Method Categories
- Category
- Key Methods
- Messages
- sendMessage
- ,
- sendPhoto
- ,
- sendVideo
- ,
- sendDocument
- ,
- editMessageText
- ,
- deleteMessage
- Keyboards
- InlineKeyboardMarkup
- ,
- ReplyKeyboardMarkup
- ,
- answerCallbackQuery
- Chat Mgmt
- getChat
- ,
- banChatMember
- ,
- promoteChatMember
- ,
- setChatPermissions
- Files
- getFile
- ,
- sendMediaGroup
- ,
- sendDocument
- Inline Mode
- answerInlineQuery
- with
- InlineQueryResult*
- types
- Payments
- sendInvoice
- ,
- answerPreCheckoutQuery
- (use
- currency: "XTR"
- for Telegram Stars)
- Bot Config
- setMyCommands
- ,
- setMyDescription
- ,
- setWebhook
- Deployment Options
- PM2
- :
- pm2 start bot.js --name telegram-bot
- - Process manager with auto-restart
- Docker
-
- Containerized deployment with
- docker-compose
- Serverless
-
- Webhook handler as Vercel/AWS Lambda function
- VPS
- Direct deployment with systemd service See reference/patterns_and_examples.md for Docker, PM2, and serverless deployment configurations. Security Checklist Store BOT_TOKEN in environment variables Validate X-Telegram-Bot-Api-Secret-Token on webhook endpoints Verify user IDs for admin commands Implement per-user rate limiting Sanitize user input before database storage Use HTTPS for all webhook endpoints Restrict allowed_updates to only needed types Reference Files For detailed API documentation and implementation patterns, consult: reference/api_methods.md - Complete list of 100+ Bot API methods organized by category (messaging, chat management, stickers, payments, inline mode, games, forum topics, gifts, passport, and more) reference/api_types.md - Complete list of 200+ Bot API types with all fields (Update, Message, Chat, User, keyboards, media types, payment types, chat members, reactions, and more) reference/patterns_and_examples.md - Production-ready implementation patterns for Node.js and Python including: inline keyboards, webhooks, media handling, conversation state management, database integration, admin panels, multi-language support, Docker/PM2/serverless deployment, Telegram Stars payments, and inline mode When building a bot, start with SKILL.md for core concepts, then load the appropriate reference file for detailed API information or implementation patterns as needed.